 Copyright (c) 1999, 2009, Oracle and/or its affiliates. All rights reserved. 

  NAME
     	README.txt -  ORACLE Multimedia Image Sample Application

                        =====================================

Contents
=======================
        Introduction
        About the Sample Application
        Requirements for Running the Sample Application
        Setup and Build the Sample Application
        Running the Sample Application
        Removing schema objects

Introduction
============
This README.txt file describes the steps required to build and run the 
Oracle Multimedia image sample applcation.  The sample application
is one of the examples on Oracle Database Examples media which is
available for download from Oracle Technology Network.

The Oracle Multimedia image sample application files are located in
<ORACLE_HOME>/ord/img/demo (on UNIX), and 
<ORACLE_HOME>\ord\img\demo (on Windows NT), where 
<ORACLE_HOME> is the ORACLE_HOME directory.

About the Sample Application
==============
The file imgdemo.c is a sample program that shows how Oracle Multimedia image
can be used from within a program. The sample is written in C and uses Oracle
Call Interface (OCI) to access the database and exercise Oracle Multimedia
image features. 

The program operates on imgdemo.bin, which is a bitmap (BMP) image in the demo
directory. Optionally, you can supply an image file name on the command line, 
provided the file resides in the same directory as the sample application. In 
either case, once the image has been manipulated by Oracle Multimedia image, 
the resulting image is written to the file imgdemo.out and can then be viewed 
with common rendering tools.

When the application is run, it prompts for a username and password in the 
default database. After values are provided for username and password, the 
application connects to the default database using the provided username, 
and deletes and re-creates a table named IMGDEMOTAB. This table is used to 
hold the sample application data. 

Once the table is created, a reference to the image file is inserted into 
the table. The data is then loaded into the table and converted to JFIF 
using the processCopy( ) method of ORDImage. The image properties are then 
extracted with the setProperties method. An UPDATE command is issued after 
the setProperties invocation to update the type attributes in the database.   
Next, the Oracle Multimedia image process( ) method is used to cut and 
scale the image within the database.  The program cuts a portion of the 
image 100 pixels wide by 100 pixels high starting from pixel location 
(100,100).  This subimage is scaled to twice its original size and the 
resulting image is written out to the file system in a file named imgdemo.out.

Upon completion, the sample application leaves the imgdemo.out file in the 
current directory. It also leaves the table IMGDEMOTAB in the specified schema 
of the database. 


Requirements for Running the Sample Application
===============================================
      o Install Oracle with Oracle Multimedia 

      o A user with create table, create any directory, and drop any directory
        privileges in which to run the demo.


Setup and Build the Sample Application
======================================

1) Use the script setup.sql to create the image demo directory:

    Decide what username will run the sample application and
    run setup.sql from SQL*Plus while connected as the same user.

    Start SQL*Plus and connect as the user under which you will
    run this sample application.

    SQL> @<ORACLE_HOME>/ord/img/demo/setup.sql (on Linux/UNIX)
         @<ORACLE_HOME>/ord/img/demo/setup.sql (on Windows)


2) Make the imgdemo program. 

    On most UNIX systems:

->  % cd <ORACLE_HOME>/ord/img/demo
->  % make -f demo_ordimg.mk imgdemo

    On Windows

->  % cd <ORACLE_HOME>/ord/img/demo
->  % make.bat

    This is operating system specific. See the installation and 
    configuration guide for your operating system for details on how
    to make this program on your operating system.


Running the Sample Application
==============================

Execute the sample application by typing imgdemo on the command line.
Optionally, an image other than imgdemo.bin can be used in the sample 
application by first copying the file to the directory in which the 
sample application resides and then specifying its file name on the 
command line as an argument to imgdemo. 

Use the following command: 

    % imgdemo <optional-image-filename>

The sample application first prompts for a username and password with which 
to connect to the default database as follows:
   
    Username: (waiting for input value)

    Password: (waiting for input value)
   

After accepting the username and password, the sample application continues
by displaying a number of messages describing its progress, along with any 
errors encountered in the event that something was not set up correctly. 
Expect to see the following messages: 

Dropping table IMGDEMOTAB... 
Creating and populating table IMGDEMOTAB... 
Loading data into cartridge... 
Modifying image characteristics... 
Writing image to file imgdemo.out... 
Disconnecting from database... 
Logged off and detached from server. 
Demo completed successfully. 

If the program encounters any errors, it is likely that either Oracle
Multimedia software has not been installed correctly or the database has 
not been started. If the program completes successfully, the original 
image and the resultant image, which has undergone the cutting and scaling 
described earlier, can be viewed with common image rendering tools.

Removing schema objects
=======================
You can use the script remove.sql to drop schema objects that are related
to this sample application. This includes the table IMGDEMOTAB in the 
specified schema and the directory IMGDEMODIR.

    Start SQL*Plus and connect to the database with the user under which
    you ran the application

    SQL> @<ORACLE_HOME>/ord/img/demo/remove.sql (on Linux/UNIX)
         @<ORACLE_HOME>/ord/img/demo/remove.sql (on Windows)

=======================
END OF README.txt
